Embedding, Viewers, Part Factoring, and Cross-Part Compatibility
By the Apple Computer OpenDoc Human Interface Team
As published in the August 1995 Apple Directions
Here’s the latest list of frequently asked design questions about OpenDoc software, and their answers, from the Apple Computer, Inc., OpenDoc human interface team. If you’re not doing OpenDoc programming yet (heaven forbid!), this column will help you get an idea of what’s at stake when you design OpenDoc components.
Q: I still have some conceptual questions about the boundaries of what should and should not be done with OpenDoc containers/parts. In particular, I am envisioning a data-flow application. Imagine that a set of parts, such as blenders, filters, and amplifiers, are “connected” together. There are also two types of containers that contain parts connected to each other in specific ways, one where these parts are “user-wirable” such that the positions cannot be changed and parts can not be added or removed (but the embedded parts can be edited); and the other where the connections between the parts are “hard-wired” and only specific types of parts can be added and removed (those that are compatible with the data-flow application). The parts can provide a user interface: A filter can have a pop-up menu for the amount of filtering, and a blender can have some GUI controls to control how much each source should be blended for the final output.
How should the parts be connected? Can I use OpenDoc to control the topology of how one part is positioned, oriented, and connected with respect to another? Or is this an abuse? Further, what kind of restrictions does OpenDoc place on how parts can be connected to each other? The underlying implication is that a part’s behavior is dependent on other parts to which it is connected. Is this against the philosophy of OpenDoc?
A: The content kind suggests the appropriate functionality your editor should provide. For example, an editor for a drawing typically provides alignment and layering operations, while editors for text or spreadsheets do not. Certainly, your editor can control how it allows parts to be connected—you are the one who decides what is appropriate.
Generally, we encourage developers to allow any kind of part to be embedded. However, in some situations, it’s appropriate for a container to only allow certain parts to be embedded. For your application, for example, it may not make sense to allow the user to embed a sound part in your container. Or, it may make sense to allow other parts to be embedded, but not allow them to be connected to the other parts. For example, a sound part could be embedded and used to store a message about the purpose of the container.
To answer your second question, you can indeed implement two types of containers to do what you describe. However, you can achieve the same results by providing a “lock-like” function in your container. The “lock” is considered a setting on the container. For further detail, see page 58 in the OpenDoc Human Interface Guidelines.
Parts were designed to permit communication with other parts by means of the extension mechanism. Check out the “Extending OpenDoc” chapter in the OpenDoc Programmer’s Guide.
Q: Can my container draw a graphical representation of the interconnections of its embedded parts?
A: Of course. You may want to have additional presentations as well. For example, you may also want to show a list view (ordered by name of component, perhaps?), or an outline view so that some groups of parts can be collapsed—whatever you think would be useful to your users. The View menu is the ideal vehicle for letting the user choose how to display parts; for further detail on using the View menu, see page 63 of the OpenDoc Human Interface Guidelines.
Q: I have a question about read-only documents. We have a requirement for allowing local developers to customize our maintenance console for particular installations. The end-user, however, should not be able to accidentally rearrange the maintenance console. I envision a local developer creating a “maintenance console” document, and providing that along with our document shell to the user. Can we “lock” this document so that the user can’t move stuff around or damage it in any way? The user would not alter the content of our document, but would just view it. Does this make sense? Should I allow the user to do anything to the document?
A: There’s no standard mechanism for what you describe, but it makes sense for some containers to supply a “lock” setting. You must use your discretion. Generally we think you should allow the user to edit the document, but the changes can only be saved through the Save A Copy command to a new document.
Q: I’m writing a viewer for my kind of content because I want users to always be able to see my kind of part. In what ways should my viewer differ from an editor?
A: A viewer is extremely handy for doing exactly what you want: making sure that users can always read and print content created by your editor. There are several significant differences between editors and viewers. First, your viewer should disable commands that allow the user to modify the contents of any part that the viewer is handling. That is, the Cut, Paste, Clear, and Insert menu commands should be dimmed. The Delete key should also be disabled. If your editor takes keyboard input (for example, if your editor is a text part), then your corresponding viewer should ignore the keystrokes.
Furthermore, because the user needs some feedback indicating that the system saw the keystrokes (text input or deletion) and decided to ignore them, you should play the system beep. If the user keeps pressing keys, you may want to display a dialog box saying something like “This content cannot be modified by typing. Keystrokes will be ignored.”
In addition, your viewer should not accept a drop (the end of a drag-and-drop) operation. You should also remove menu commands such as Font Size. It doesn’t make sense to simply disable these operations, because the user can’t make them available.
Editors should display splash screens as infrequently as possible—subject to legal requirements. However, we encourage you to let your viewer display its splash screen occasionally. Viewers are free—and you’re providing a service to users by letting them look at content they might not otherwise be able to view. So, feel free to have your viewer display a splash screen occasionally to remind users that you also have a full-featured product in which they might be interested.
And finally, make sure that the icon for your viewer looks like a viewer icon and not an editor icon. To see the differences, see the examples in the OpenDoc Human Interface Guidelines.
Q: I’m breaking my application up into OpenDoc parts, and I’m having some doubts about how to divide up the functionality among the parts. Do you have any advice?
A: The underlying issue is granularity, one of the most difficult parts of designing for OpenDoc. The reason for this difficulty is that you are trying to anticipate what users want. Choosing where to put part boundaries is as much art as science, and you should take the time to do it right, because it will make a big difference in the success of your product.
One of the best approaches is to “make up stories” about what the user will do. As an example, here are two stories, one for someone using a database report, and one for someone creating that report in the first place.
The first story goes something like this: A user is reading a document and sees a button labeled with the name of some database report mentioned in the document. He presses the button, and a report appears in a separate window.
The second story might go like this: A power user is creating a document, and she wants to include a report from a database that’s available within the company. She creates a special “report button” that will display the report. The report itself has a bit of text and a chart. The user creates a form-like document with a little spreadsheet to calculate the chart values and links the spreadsheet to the database using a database-query part. She then creates a chart, links it to the spreadsheet, adds an explanatory paragraph, and then hides the spreadsheet and database part from the reader. The resulting form is dropped into the “report button” where it is ready for later examination by a reader.
Now the next trick is to look for the “natural” breaks in the parts at hand, based on the way you phrase the stories. Try to phrase the stories without using jargon; if you can easily phrase them without inventing new terms, it’s likely that ordinary people will understand where the boundaries are between the parts. If you do use jargon, make sure it’s commonly used by your target customers. (Reading magazines is a pretty good way to find out the common jargon, since they specialize in being understandable.)
The first story involves using a button to display a “hidden” report. You want to let people include reports as an annotation, of sorts. Is a button the best way to do it? That depends on your user, but since a lot of people understand pressing buttons to get more information, it’s a pretty good device.
The second story involves a power user or programmer putting together a “canned” report. The story mentions several “natural” elements—query, button, chart, and spreadsheet. Implicit in the scenario is a container—probably something like a forms container.
It would probably be best to make each of these items a separate part, and then use linking and scripting to hook them up.
To be specific, you might make a scriptable database query part that can be the source of a link, and use a spreadsheet part as the destination of the link to display the results. The spreadsheet part would have the usual features for formulas and such. The chart part would have formatting features for fonts, 3D bars, and the like.
You might create a scriptable forms part that can serve as a layout tool and as a source of input for the query if needed. The forms part would also be able to hide embedded elements, so that users would only see the forms elements and table. This hiding feature is really just a formatting tool, not a required feature, but any editor can provide this feature if it makes sense. A word processor or page layout editor might provide this capability.
Finally, I’d use a button part to open the forms part and cause it to update with query results. This “annotation button” part would remember the forms part (or any embedded part) as well as run a script when the button is pressed. The button would then be embedded wherever the user wanted to put the canned report.
The advantage of this approach is that you have a powerful set of general-purpose tools to sell, rather than a single, specific part. Each of the parts can be reused in a different solution later: The forms tool might be used to create simple entry pads, instead of being a database display mechanism; the button might display other kinds of annotation, not just canned reports; and the spreadsheet part might be used to display the results of non-database links or just tables entered “by hand.” (The database query part alone is a relatively single-purpose part.)
The fact that the annotation button, the forms package, and the spreadsheet are such generically useful tools also suggests something else: that other developers may be building them and that you could license these tools for inclusion in your own product, rather than building them all yourself.
Q: What will happen when users try to integrate parts that were created by different part developers, but that were not tested together for compatibility? Who does the user call if the parts are not compatible with one another?
A: This question has two answers. The first answer speaks to you, the developer. The second answer speaks (as well as the situation permits) to the user’s predicament.
To the developer: Component Integration Laboratories (CI Labs) will provide a validation suite that developers can use to validate their code to ensure that their editors meet a minimum set of integration criteria. If you wish, CI Labs will also validate your editor with many other editors, for a fee. Editors that receive the CI Labs sticker are guaranteed to meet the integration criteria; however, this does not guarantee that all of the parts a user wants to use will work well with each other. Of course, vendors are ultimately responsible for making sure the editors work; CI Labs can help to make sure they work with each other.
As a developer, if you discover an integration problem, you should inform your platform vendor (for example, Apple, IBM, or Novell) and CI Labs so that the validation process can be improved.
To the user: You can find out who to call either by making the part active and looking at the “About” box, or by selecting the part and choosing the Part Info command from the Edit menu. Then you will have to work with the vendors of both parts to determine which part is in error (or whether some other circumstance is causing the error).
We know that’s not the solution you want to hear, but it’s the only one the situation permits. In fact, it’s no different than what you have to do when you get an error that you suspect may be caused by a third-party extension.
